

    \filetitle{series}{Add new data to graph or table}{report/series}

	\paragraph{Syntax}

\begin{verbatim}
P.series(Cap,X,...)
\end{verbatim}

\paragraph{Input arguments}

\begin{itemize}
\item
  \texttt{P} {[} struct {]} - Report object created by the
  \href{report/new}{\texttt{report.new}} function.
\item
  \texttt{Cap} {[} char \textbar{} cellstr \textbar{} \texttt{@auto} {]}
  - Caption used as a default legend entry in a graph, or in the leading
  column in a table; \texttt{@auto} means that the first comment from
  the input tseries object, \texttt{X}, will be used for the title.
\item
  \texttt{X} {[} tseries {]} - Input data that will be added to the
  current table or graph.
\end{itemize}

\paragraph{Options for both table series and graph
series}

\begin{itemize}
\item
  \texttt{\textquotesingle{}marks=\textquotesingle{}} {[} cellstr
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) Marks
  that will be added to the legend entries in graphs, or printed in a
  third column in tables, to distinguish the individual columns of
  possibly multivariate input tseries objects.
\item
  \texttt{\textquotesingle{}showMarks=\textquotesingle{}} {[}
  \emph{\texttt{true}} \textbar{} \texttt{false} {]} - (Inheritable from
  parent objects) Use the marks defined in the
  \texttt{\textquotesingle{}marks=\textquotesingle{}} option to label
  the individual rows when input data is a multivariate tseries object.
\end{itemize}

\paragraph{Options for table series}

\begin{itemize}
\item
  \texttt{\textquotesingle{}autoData=\textquotesingle{}} {[}
  function\_handle \textbar{} cell \textbar{} \emph{empty} {]} -
  Function, or a cell array of functions, that will be used to produce
  new columns in the input tseries object (i.e.~new rows of ouput in the
  report).
\item
  \texttt{\textquotesingle{}condFormat=\textquotesingle{}} {[} struct
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects)
  Structure with .test and .format fields describing conditional
  formatting of individual table entries.
\item
  \texttt{\textquotesingle{}decimal=\textquotesingle{}} {[} numeric
  \textbar{} \emph{\texttt{NaN}} {]} - (Inheritable from parent objects)
  Number of decimals that will be displayed; if NaN the
  \texttt{\textquotesingle{}format=\textquotesingle{}} option is used
  instead.
\item
  \texttt{\textquotesingle{}format=\textquotesingle{}} {[} char
  \textbar{} \emph{\texttt{\textquotesingle{}\%.2f\textquotesingle{}}}
  {]} - (Inheritable from parent objects) Numeric format string; see
  help on the built-in \texttt{sprintf} function.
\item
  \texttt{\textquotesingle{}footnote=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - Footnote at the series text.
\item
  \texttt{\textquotesingle{}highlight=\textquotesingle{}} {[} numeric
  \textbar{} \emph{empty} {]} - Periods for which the data entries will
  highlighted.
\item
  \texttt{\textquotesingle{}inf=\textquotesingle{}} {[} char \textbar{}
  \emph{\texttt{\textquotesingle{}\textbackslash{}ensuremath\{\textbackslash{}infty\}\textquotesingle{}}}
  {]} - (Inheritable from parent objects) LaTeX string that will be used
  to typeset Inf entries.
\item
  \texttt{\textquotesingle{}nan=\textquotesingle{}} {[} char \textbar{}
  \emph{\texttt{\textquotesingle{}\textbackslash{}ensuremath\{\textbackslash{}cdot\}\textquotesingle{}}}
  {]} - (Inheritable from parent objects) LaTeX string that will be used
  to typeset NaN entries.
\item
  \texttt{\textquotesingle{}pureZero=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) LaTeX
  string that will be used to typeset pure zero entries; if empty the
  zeros will be printed using the current numeric format.
\item
  \texttt{\textquotesingle{}printedZero=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - (Inheritable from parent objects) LaTeX
  string that will be used to typeset the entries that would appear as
  zero under the current numeric format used; if empty these numbers
  will be printed using the current numeric format.
\item
  \texttt{\textquotesingle{}rowHighlight=\textquotesingle{}} {[}
  \texttt{true} \textbar{} \emph{\texttt{false}} {]} - Highlight the
  entire row, including the text, units and marks at the beginnig;
  because of a bug in the LaTex package \texttt{colortbl}, this option
  cannot be combined with the option
  \texttt{\textquotesingle{}highlight=\textquotesingle{}} in
  \href{report/table}{\texttt{report/table}}.
\item
  \texttt{\textquotesingle{}separator=\textquotesingle{}} {[} char
  \textbar{} \emph{empty} {]} - LaTeX commands that will be inserted
  immediately after the end of the table row, i.e.~appended to
  \textbackslash{}, within a tabular mode.
\item
  \texttt{\textquotesingle{}units=\textquotesingle{}} {[} char {]} -
  (Inheritable from parent objects) Description of input data units that
  will be displayed in the second column of tables.
\end{itemize}

\paragraph{Options for graph series}

\begin{itemize}
\item
  \texttt{\textquotesingle{}legendEntry=\textquotesingle{}} {[} char
  \textbar{} cellstr \textbar{} \texttt{NaN} \textbar{}
  \emph{\texttt{@auto}} {]} - Legend entries used instead of the series
  caption and marks; \texttt{@auto} means the caption and marks will be
  used to construct legend entries; \texttt{NaN} means the series will
  be exluded from legend.
\item
  \texttt{\textquotesingle{}plotFunc=\textquotesingle{}} {[}
  \texttt{@area} \textbar{} \texttt{@bar} \textbar{} \texttt{@barcon}
  \textbar{} \emph{\texttt{@plot}} \textbar{} \texttt{@plotcmp}
  \textbar{} \texttt{@plotpred} \textbar{} \texttt{@stem} {]} -
  (Inheritable from parent objects) Plot function that will be used to
  create graphs.
\item
  \texttt{\textquotesingle{}plotOptions=\textquotesingle{}} {[} cell
  \textbar{} \emph{empty} {]} - Options passed as the last input
  arguments to the plot function.
\item
  \texttt{yAxis=\textquotesingle{}} {[}
  \emph{\texttt{\textquotesingle{}left\textquotesingle{}}} \textbar{}
  *\texttt{\textquotesingle{}right\textquotesingle{}} {]} - Choose the
  LHS or RHS axis to plot this series; see also comments on LHS-RHS
  plots in Description.
\end{itemize}

\paragraph{Generic options}

See help on \href{report/Contents}{generic options} in report objects.

\paragraph{Description}

\subparagraph{\texorpdfstring{Using the options
\texttt{\textquotesingle{}nan=\textquotesingle{}},
\texttt{\textquotesingle{}inf=\textquotesingle{}},
\texttt{\textquotesingle{}pureZero=\textquotesingle{}} and
\texttt{\textquotesingle{}printedZero=\textquotesingle{}}}{Using the options 'nan=', 'inf=', 'pureZero=' and 'printedZero='}}

When specifying the LaTeX string for these options, bear in mind that
the table entries are printed in the math model. This means that
whenever you wish to print a normal text, you need to use an appropriate
text formatting command allowed within a math mode. Most frequently, it
would be
\texttt{\textquotesingle{}\textbackslash{}textnormal\{...\}\textquotesingle{}}.

\subparagraph{\texorpdfstring{Using the option
\texttt{\textquotesingle{}plotFunc=\textquotesingle{}}}{Using the option 'plotFunc='}}

When you set the option to
\texttt{\textquotesingle{}plotpred\textquotesingle{}}, the input data
\texttt{X} (second input argument) must be a multicolumn tseries object
where the first column is the time series observations, and the second
and further columns are its Kalman filter predictions as returned by the
\texttt{filter} function.

\subparagraph{Conditional formatting}

The conditional format struct (or an array of structs) specified through
the \texttt{\textquotesingle{}condFormat=\textquotesingle{}} option must
have two fields, \texttt{.test} and \texttt{.format}.

The \texttt{.test} field is a text string with a Matlab expression. The
expression must evaluate to a scalar true or false, and can refer to the
following attributes associated with each entry in the data part of the
table:

\begin{itemize}
\tightlist
\item
  \texttt{value} - the numerical value of the entry,
\item
  \texttt{date} - the date under which the entry appears,
\item
  \texttt{year} - the year under which the entry appears,
\item
  \texttt{period} - the period within the year (e.g.~month or quarter)
  under which the entry appears,
\item
  \texttt{freq} - the frequency of the date under which the entry
  appears,
\item
  \texttt{text} - the text label on the left,
\item
  \texttt{mark} - the text mark on the left used to describe the
  individual rows reported for multivariate series,
\item
  \texttt{row} - the row number within a multivariate series.
\item
  \texttt{rowvalues} - a row vector of all values on the current row.
\end{itemize}

If the table is based on user-defined structure of columns (option
\texttt{\textquotesingle{}colstruct=\textquotesingle{}} in
\href{report/table}{\texttt{table}}), the following additional
attributes are available

\begin{itemize}
\tightlist
\item
  \texttt{colname} - descriptor of the column (text in the headline).
\end{itemize}

You can combine a number of attribues within one test, using the logical
operators, e.g.

\begin{verbatim}
'value > 0 && year > 2010'
\end{verbatim}

The \texttt{.format} fields of the conditional format structure consist
of LaTeX commands that will be use to typeset the corresponding entry.
The reference to the entry itself is through a question mark. The
entries are typeset in math mode; this for instance meanse that for bold
or italic typface, you must use the
\texttt{\textbackslash{}mathbf\{...\}} and
\texttt{\textbackslash{}mathit\{...\}} commands.

In addition to standard LaTeX commands, you can use the following
IRIS-specific commands in the format strings:

\begin{itemize}
\item
  \texttt{\textbackslash{}sprintf\{FFFF\}} - to modify the way each
  numeric entry that passes the test is printed by the \texttt{sprintf}
  function; \texttt{FFFF} is one of the standard \texttt{sprintf}
  formatting strings.
\item
  \texttt{\textbackslash{}hide\{?\}} - to hide the actual entry when it
  is supposed to be replaced with something else.
\end{itemize}

You can combine multiple tests and their correponding formats in one
structure; they will be all applied to each entry in the specified
order.

\subparagraph{LHS-RHS plots}

The LHS-RHS report graphs are still an experimental feature.

When the option \texttt{\textquotesingle{}yAxis=\textquotesingle{}} is
used to plot on both the LHS and the RHS y-axis, the plot functions are
restricted to \texttt{@plot}, \texttt{@bar}, \texttt{@area} and
\texttt{@stem}. Also, because of a bug in Matlab, always control the
color of the lines, bars and areas in all LHS-RHS graphs: use either the
option \texttt{\textquotesingle{}plotOptions=\textquotesingle{}} in this
command, or \texttt{\textquotesingle{}style=\textquotesingle{}} in the
respective \href{report/graph}{\texttt{graph}} command.

\paragraph{Example (Conditional format
structure)}

Typeset negative values in italic, and values in periods before 2010Q1
blue:

\begin{verbatim}
cf = struct();
cf(1).test = 'value < 0';
cf(1).format = '\mathit{?}';
cf(2).test = 'date < qq(2010,1)';
cf(2).format = '\color{blue}';
\end{verbatim}


